Last updated on 8/23/00

ListBox Widget

/widgets/listHTC/listbox.htc

The ListBox control allows easy list operations on a nested DIV structure. Here's an example using two ListBoxes for list creation:

value 1
value 2
value 3
value 4
value 5







Event log:


events

OnSelect
fires when an item selected

event object properties

none

OnUnselect
fires when an item unselected

event object properties

none

OnSelectAll
fires when an all items selected using selectall method

event object properties

none

OnUnselectAll
fires when an all items unselected using unselectall method

event object properties

none

OnChange
fires when items are added or removed from the ListBox

event object properties

none

methods

elListBox.SelectAll()
selects all items in the list

parameters

none

return value

none

elListBox.UnselectAll()
unselects all items in the list

parameters

none

return value

none

elListBox.select(sValue)
selects the first item found whose value is equal to sValue. If not found nothing is selected and no error is returned.

parameters

sValue Required. Value of item to select.

return value

none

elListBox.unselect(sValue)
unselects the first item found whose value is equal to sValue. If not found nothing is unselected and no error is returned.

parameters

sValue Required. Value of item to unselect.

return value

none

elListBox.addItem(sValue, sText)
Creates a new item in the list with the va;lue and text passed in

parameters

sValue Required. Value of new item.

sText Required. display text of new item.

return value

none

elListBox.add(xmlNodes)
Adds items correcsponding to xml nodes passed in. Consumes xml format returned by remove()

parameters

xmlNodes Required. xmlNodes with value attribute and text that will be used for new items.

return value

none

set xmlNodes = elListBox.remove()
Removes all selected items and returns aml node for each one

parameters

none

return value

xmlNodes xmlNodes with value attribute and text that from removed items.

elListBox.moveup()
Move selected item up one place in the list. In the case of multi-select, will either move last selected item or the first selected item in the list.

parameters

none

return value

none

elListBox.movedown()
Move selected item down one place in the list. In the case of multi-select, will either move last selected item or the first selected item in the list.

parameters

none

return value

none

container attributes (set on element using ListBox behavior)

selection 'multi' or 'single', (default = single)
lbDisabled Note: add this style class in addition to 'ListBox' to make the ListBox initially disabled

scriptable properties

bDisabled = elListBox.disabled
elListBox.disabled = bDisabled
Read-write. Returns true if the ListBox is disabled (grayed-out and removed from tab order), false otherwise.
set elSelected = elListBox.selected
Read-only. Gets currently selected element for single selection ListBox. In the case of multi-select, will either return last selected item or the first selected item in the list.
sText = elListBox.text
elListBox.text = sText
Read-write. Gets or sets text for currently selected item for single selection ListBox. In the case of multi-select, will either set/return text for last selected item or the first selected item in the list.
sValue = elListBox.value
elListBox.value = sValue
Read-write. Gets or sets underlying value for currently selected item for single selection ListBox. In the case of multi-select, will either set/return underlying value for last selected item or the first selected item in the list.

meta-xml

DataXML

Unlike other widgets, the ListBox does not draw anything new into the document. It just formats a nested DIV structure. The structure it expects is as follows (note the close correlation to the SELECT/OPTION elements):
	<DIV CLASS='ListBox' selection='multi'>
		<DIV VALUE='val1'>value 1</DIV>
		<DIV VALUE='val2'>value 2</DIV>
		…
		<DIV VALUE='valn'>value n</DIV>
	<DIV>